# *[Проект SoftSpiders](https://github.com/softspider)*

<p align="center">
  <a href="https://github.com/softspider">
    <img src="./images/sslogo-from-github-40.png" />
  </a>
</p>

## Оглавление
1. [Предназначение](#предназначение) 
    1. [В чём проблема](#в-чём-проблема)
    2. [Быстрое прототипирование прототипов](#Быстрое-прототипирование-прототипов)
    3. [Классификатор *SoftSpiders*](#классификатор-softspiders)
    4. [Прототипы *SoftSpiders*](#прототипы-softspiders)
    5. [Классификатор программных решений](#классификатор-программных-решений)
    6. [Сопутствующие задачи](#сопутствующие-задачи)
2. [Принципы организации *SoftSpiders*](#принципы-организации-softspiders)
    1. [С чего начинается разработка](#с-чего-начинается-разработка) 
    2. [Зачем нужна минималистичность](#зачем-нужна-минималистичность) 
    3. [Иерархия минималистичных прототипов](#иерархия-минималистичных-прототипов) 
3. [Иерархия прототипов](#иерархия-прототипов)
    1. [*Свойства* и *теги*](#свойства-и-теги) 
    2. [DAG-иерархия](#dag-иерархия) 
    3. [Если кратко](#если-кратко) 
    4. [Пример](#пример) 
    5. [Текущая реализация](#текущая-реализация) 
4. [Базовые сценарии](#базовые-сценарии)
    1. [Поиск прототипа](#поиск-прототипа) 
    2. [Создание прототипа](#создание-прототипа) 
    3. [Декомпозиция сложного прототипа](#декомпозиция-сложного-прототипа) 
    4. [Создание тега-свойства](#создание-тега-свойства) 
5. [FAQ](#faq)
    1. [Какие проблемы решает *SoftSpiders*?](#какие-проблемы-решает-softspiders-) 
    2. [Зачем нужны прототипы?](#зачем-нужны-прототипы-) 
    3. [Почему недостаточно библиотек?](#почему-недостаточно-библиотек-) 
    4. [Сохраняется ли авторство у разработчиков прототипов ?](#сохраняется-ли-авторство-у-разработчиков-прототипов-) 
    5. [На каких технологиях реализован проект ?](#на-каких-технологиях-реализован-проект-) 
    6. [Предполагается ли платное использование сервиса ?](#предполагается-ли-платное-использование-сервиса-) 
    7. [Что делать, если у зависимостей изменяются версии ?](#что-делать-если-у-зависимостей-изменяются-версии-) 
6. [Словарь используемых тегов](#словарь-используемых-тегов)
    1. [Правила именования тегов](#правила-именования-тегов) 
    2. [Теги-синонимы](#теги---синонимы) 
    3. [Зависимости тегов](#зависимости-тегов) 
    4. [Эффективные наборы тегов](#эффективные-наборы-тегов) 
    5. [Пояснения к тегам](#пояснения-к-тегам) 
7. [Текущее состояние проекта](#текущее-состояние-проекта)
    1. [Эволюция и перспективы проекта](#эволюция-и-перспективы-проекта) 
    2. [Что нужно прямо сейчас](#что-нужно-прямо-сейчас) 
    3. [Что потребуется в ближайшее время](#что-потребуется-в-ближайшее-время) 
8. [Приложения](#приложения)
    1. [Правила разработки прототипа](#правила-разработки-прототипа) 
    2. [Правила оформления README](#правила-оформления-readme) 

---

# Предназначение 

Если кратко, *[SoftSpiders](https://github.com/softspider)* можно охарактеризовать как проект создания **классификатора
программных решений**, создаваемого разработчиками для разработчиков.  

## В чём проблема 

Поиск качественного прототипа - программного решения, которое можно было бы использовать в качестве основы для новой
разработки является непростой задачей, к тому же она не всегда завершается успехом.  

Чем больше свойств, которыми прототип должен обладать, тем больше его сложность и тем меньше шансов его найти в готовом
для использования виде.

Сегодня для разработчика, который ищет подходящую основу для начала разработки, почти все пути ведут в
[GitHub](https://github.com/), с появлением которого задача нахождения программного кода с нужными свойствами
значительно упростилась.    
Но и в этом случае вся совокупность необходимых действий: работа с поисковиком, проверка качества исходников и
работоспособности программ до сих пор требует немалых навыков и усилий, которые к тому же очень часто оказываются
неблагодарными.

Главная задача проекта *SoftSpiders* заключается в попытке решения этой проблемы.  

## Быстрое прототипирование прототипов 

### Быстрое прототипирование

Предназначение *SoftSpiders* во многом состоит в том, чтобы хорошие прототипы можно было легко находить, сравнивать,
выбирать и использовать по назначению, ускоряя и удешевляя создание разнообразных программных продуктов.  
И с этой точки зрения *SoftSpiders* можно формально позиционировать как **средство быстрого прототипирования**.

### Прототипирование прототипов 

Но в отличие от многих других средств прототипирования *SoftSpiders* характерен тем, что его главной задачей является не
столько генерация готовых программ (хотя она тоже может решаться), сколько систематизация уже существующих прототипов и -
на преемственной основе - **упрощение процесса создания самих прототипов**, что делает его своеобразным ***средством
прототипирования прототипов***.

Основой систематизации прототипов служит классификатор *SoftSpiders*. 

## Классификатор *SoftSpiders*

Для лучшего понимания механизмов организации классификатора *SoftSpiders*, сразу стоит отметить, что его содержательными
единицами (далее по тексту - элементами) не обязательно должны быть прототипы.

### Не обязательно прототипы

*Элементом классификатора *SoftSpiders* может быть любой набор текстовых файлов, если этому набору можно сопоставить
какое-то подмножество из **общего множества свойств**.*

Например, элементами классификатора могут быть:

- шаблоны текстовых документов
- кулинарные рецепты (ингредиенты могут выступать свойствами)
- заготовки учебных (и других) планов
- заготовки различных сценариев
- ...

**Общее множество свойств** является систематизирующей основой классификатора. Оно определяет границы, в которых будут
существовать его содержательные элементы.

Но при всех имеющихся возможностях классифицировать разное сам проект *SoftSpiders* ориентирован прежде всего на
систематизацию *программных прототипов*, на создание сервисов, упрощающих жизнь разработчиков программ.

## Прототипы *SoftSpiders*

Какие виды прототипов поддерживает проект ?

### Программные прототипы

В *SoftSpiders* предполагается поддежка следующих видов программных прототипов:

- проекты-стартеры
- шаблоны (исходники для разнообразных генераторов)
- образовательные проекты - проекты, используемые для обучения/самообучения
- архитектурные решения (шаблоны проектирования, ...)
- алгоритмы
- конфигурации (Webpack, pom, package.json, Travis CI, Docker, ...)
- раскладки (layout) экранов пользовательского интерфейса
- ...

## Классификатор программных решений

Классификатор *SoftSpiders* организован как иерархия прототипов, которая снабжена средствами создания, поиска и
навигации по иерархии прототипов.

Ниже по тексту иерархию *SoftSpiders* будем сокращённо называть ***SS-иерархией***, а прототипы *SoftSpiders* -
***SS-прототипами***.

Предполагается, что эта база должна охватывать все виды программной разработки без каких бы то ни было ограничений.

## Сопутствующие задачи 

Среди задач, которые призван решать *SoftSpiders*, можно выделить ещё, как минимум, те, что направлены на обеспечение
обмена опытом между разработчиками: 
- помощь при самообучении
- фиксация результатов самообучения или результатов разработки в виде новых проектов
- передача знаний при обучении (иерархия качественных программных проектов представляет собой практически готовый
учебный материал)

---

# Принципы организации *SoftSpiders*

Далее о том, почему содержание *SoftSpiders* составляют минималистичные программные проекты и о принципах организации
классификатора.
 
## С чего начинается разработка

С появлением поисковиков и открытых программных репозиториев начало нового проекта всё чаще начинается с поиска готовой
и наиболее подходящей работающей программы-прототипа, которую можно было бы взять в качестве основы для дальнейшей
разработки.           

Для того, чтобы прототип наилучшим образом подходил в качестве такой основы, в нём не должно быть ничего лишнего -
только необходимое.  

## Зачем нужна минималистичность

Важным и очень желательным свойством прототипа является его ***минималистичность***, поскольку она гарантирует прототипу
сбалансированное присутствие в нём всех его свойств, упрощает пользователям-разработчикам знакомство с этим прототипом,
упрощает сравнение его с другими, родственными прототипами, в том числе при помощи diff-инструментов, особенно, если они
тоже минималистичны.

## Иерархия минималистичных прототипов

В основе *SoftSpiders* лежит классификатор (далее по тексту - *SS-классификатор*), элементами которого являются
прототипы программ.

При множественном наследовании SS-иерархия может иметь множество корней. В корнях этой иерархии  лежат простейшие
программы, являющиеся hello-world-программами в самом обычном смысле этого слова: hello-world на Java, hello-world на
JavaScript, и т.д.    
На следующих уровнях иерархии находятся хоть и более сложные, но, если их рассматривать в контексте свойств своих
предков, тоже минималистичные программы.

Каждый дочерний проект-прототип добавляет к родительскому прототипу в общем случае несколько новых свойств (в идеале -
одно), например, логирование, сборку,  тестирование, и т.п. Этот дочерний прототип, в свою очередь, становится
родительским для других новых прототипов. И так далее.
  
Таким образом в результате выстраивается ***иерархия минималистичных прототипов с поддержкой множественного наследования
свойств***
([DAG](https://ru.wikipedia.org/wiki/%D0%9E%D1%80%D0%B8%D0%B5%D0%BD%D1%82%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D1%8B%D0%B9_%D0%B0%D1%86%D0%B8%D0%BA%D0%BB%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B9_%D0%B3%D1%80%D0%B0%D1%84)-иерархия).

---

# Иерархия прототипов

SS-иерархия выглядит примерно так же, как иерархия классов или интерфейсов в ООП, с поддержкой множественного
наследования.

## *Свойства* и *теги*

Ключевым понятием SS-классификатора является понятие *свойства*.

В *SoftSpiders* поддерживается расширяемый стандартизованный перечень ***свойств***.
Каждое *свойство*, как правило, определяет некоторую функциональность - то, для чего на английском обычно используется
термин *feature*.

Каждому свойству ставится в соответствие уникальный ***тег*** (или множество *тегов-синонимов*), идентифицирующий
это свойство.

В контексте *SoftSpiders* понятия *тег* и *свойство* часто взаимозаменяемы. Но есть разница.  
В отличие от именования тегов для именования свойств не существует каких-то строгих правил - могут использоваться разные
языки, алфавиты, и т.п.

## DAG-иерархия

Каждый SS-прототип имеет какой-то определённый набор свойств и помечается соответствующим набором тегов.

Поскольку не все наборы свойств могут быть сравнимы между собой, то SS-прототипы образуют
[*частично-упорядоченное множество*](https://ru.wikipedia.org/wiki/%D0%A7%D0%B0%D1%81%D1%82%D0%B8%D1%87%D0%BD%D0%BE_%D1%83%D0%BF%D0%BE%D1%80%D1%8F%D0%B4%D0%BE%D1%87%D0%B5%D0%BD%D0%BD%D0%BE%D0%B5_%D0%BC%D0%BD%D0%BE%D0%B6%D0%B5%D1%81%D1%82%D0%B2%D0%BE),
или [DAG](https://ru.wikipedia.org/wiki/%D0%9E%D1%80%D0%B8%D0%B5%D0%BD%D1%82%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D1%8B%D0%B9_%D0%B0%D1%86%D0%B8%D0%BA%D0%BB%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B9_%D0%B3%D1%80%D0%B0%D1%84)-иерархию.

## Если кратко

*Каждый SS-прототип помечается соответствующим ему набором тегов. Поэтому иерархия SS-прототипов фактически является
иерархией наборов тегов*.

## Пример

Лучше один раз увидеть, чем сто раз услышать.

Рассмотрим простой пример, иллюстрирующий возникновение отношений родитель-потомок между прототипами, в котором также
показывается образование иерархии с множественным наследованием свойств.

Пусть прототип **A** представлен hello-world-программой на Java. Поскольку других свойств прототип **A** не имеет, то он
помечается только тегом *java* (набором тегов *{java}*):  

<p align="center"> 
<img src="./images/SimpleHierarhy-java-log4j-maven-1.png">
</p>

Пусть прототип **B** отличается от прототипа **A** только тем, что он реализован по стандартам *Maven*. В соответствии с
этим он помечается набором тегов *{java, maven}*:

<p align="center"> 
<img src="./images/SimpleHierarhy-java-log4j-maven-2.1.png">
</p>

Поскольку множество тегов прототипа **A** (*{java}*) принадлежит множеству тегов прототипа **B** (*{java, maven}*),
прототип **B** является потомком прототипа **A**.

По-другому можно сказать, что прототип *B* функционально расширяет прототип *A*, поскольку имеет более полный набор
свойств.

Пусть ещё один прототип **C** отличается от прототипа **A** только тем, что вывод сообщений выполняется в нём с помощью
библиотеки *log4j*, и в соответствии с этим он помечается набором тегов *{java, log4j}*:

<p align="center"> 
<img src="./images/SimpleHierarhy-java-log4j-maven-2.2.png">
</p>

Поскольку множество тегов прототипа **A** (*{java}*) принадлежит множеству тегов прототипа **C** (*{java, log4j}*),
прототип **C** также, как и **B**, является потомком прототипа **A**.

Пусть реализован ещё один hello-world-прототип на Java, назовём его **D**.  
Пусть он так же, как **B**, организован по стандарту
*Maven* и, так же, как **C**, выводит сообщения с помощью библиотеки *log4j*.  
Тогда в соответствии со своим набором свойств прототип **D** помечается набором тегов *{java, log4j, maven}* и согласно
вышеуказанным правилам наследования будет одновременно являться непосредственным потомком как прототипа **B**, так и
прототипа **C**.

<p align="center"> 
<img src="./images/SimpleHierarhy-java-log4j-maven-full.png">
</p>


В результате прототипы **A**, **B**, **C** и **D** образуют небольшую DAG-иерархию, в которой прототип **D** является
множественным наследником свойств прототипов **B** и **C**.

## Текущая реализация

На данный момент SS-иерархия предварительно реализована при помощи http-ссылок, размещающихся в файлах *README.md*
соответствующих git-репозиториев.  

По факту все git-репозитории находятся на *GitHub*. Пока это рекомендуемая практика, хотя она и не является обязательной. 

---

# Базовые сценарии

Рассмотрим базовые сценарии работы с прототипами. К ним относятся:
- Поиск прототипа
- Создание прототипа
- Декомпозиция сложного прототипа
- Создание свойства

### Поиск прототипа

Поиск нужного прототипа происходит путём комбинирования фильтрации по тегам и дальнейшей навигации по SS-иерархии.

Замечание: в текущей предварительной реализации используется нестрогая фильтрация на основе тегов GitHub.

#### Фильтрация по тегам

SS-иерархия обеспечивает возможность фильтрации прототипов с помощью тегов, что позволяет, варьируя наборы тегов-свойств,
оперативно изучать пространство имеющихся прототипов, после чего делать на этой основе быстрый и качественный выбор. 

#### Навигация по SS-иерархии

При навигации по SS-иерархии пользователь переходит по иерархическим связям с одного прототипа на другой, имея при этом
возможность подробного просмотра свойств, параметров, исходного кода и других деталей каждого из прототипов.
 
При навигации по иерархии предполагается, что в каждый момент времени пользователь находится на каком-то одном из её
узлов. При этом в общем случае пользователь имеет возможность перейти или на один из узлов потомков, или на один из
родительских узлов. 

В целевой реализации навигация по SS-иерархии предполагает поддержку со стороны соответствующей клиентской программы.    
Но в сегодняшней предварительной реализации навигация выполняется при помощи браузера посредством переходов по
http-ссылкам Readme-документов прототипов, размещённых на GitHub. 

### Создание прототипа

Создание прототипа предполагает следующие этапы:

1. Создание для прототипа git-репозитория (на данный момент рекомендуется использовать GitHub)
2. Разработка прототипа в созданном репозитории согласно несложным [правилам](#правила-разработки-прототипа)
3. Документирование прототипа в файле *README.md* согласно соответствующим
[правилам](#правила-оформления-readme)

### Декомпозиция сложного прототипа

Декомпозиция хорошего сложного прототипа на более простые - самый удобный и лучший способ создания прототипов, поскольку,
во-первых, разбирать проект на части гораздо легче, чем собирать, а во-вторых, в результате декомпозиции можно легко
получить целое семейство проектов, связанных между собой не только общими свойствами, но и **общим кодом**, что даёт
возможность удобо сравнивать код прототипов diff-инструментами.

### Создание тега-свойства

1. Перед тем, как создавать новый тег-свойство, необходимо убедиться, что этот тег отсутствует в
[словаре](#словарь-тегов).  
При этом необходимо понять, действительно ли речь идёт о добавлении нового свойства или требуется добавить просто новый
синоним к одному из существующих тегов-свойств.   
2. После того, как необходимость создания нового тега/синонима подтвердилась, нужно подать заявку на расширение словаря
тегов простым письмом на адрес <sftspider@gmail.com> в письменно-свободной форме (пока так).
3. Дождаться необходимых изменений в [словаре тегов](#словарь-тегов) или отказа с объяснением причин, если заявку
невозможно удовлетворить.  

---

# FAQ

## Какие проблемы решает *SoftSpiders* ?

*SoftSpiders* не решает каких-то фундаментальных проблем, но он упрощает жизнь разработчиков в таких аспектах, как:
- старт новых проектов, предлагая удобные средства поиска качественных прототипов
- создание новых прототипов - во многом за счёт их иерархической организации, что даёт возможность **инкрементальной
разработки** прототипов путём создания новых на основе старых, уже присутствующих в иерархии 
- обучение новым технологиям, предлагая классификатор прототипов как хорошую систематизацию учебных материалов
- фиксацию результатов самообучения/разработки в виде новых прототипов

## Зачем нужны прототипы ?

В первую очередь прототипы нужны для разработки.  

Разработку любого проекта намного проще начать, если взять за основу близкий по функциональности другой, уже работающий
проект. Прототипы *SoftSpiders* как раз и являются такими работающими проектами.

Но помимо помощи разработчику прототипы *SoftSpiders* играют также и образовательную роль (см. выше).

## Почему недостаточно библиотек ?

В мире программирования библиотеки являются неоценимым способом повторного использования программных решений. Но при
этом они всё же не могут удовлетворить всех потребностей, возникающих при разработке. 

По сравнению с библиотеками прототипы предлагают хотя и другой, может быть менее формализованный, но в определённом
смысле, более высокий уровень повторного использования.

### Прототипы предлагают целостные решения

В отличие от библиотек, программные прототипы представлены **работающими программами** и предлагают **целостные
решения**, что приципиально важно.

### Качественные стартеры предлагают хорошие практики
  
В частности, если говорить о библиотеках, прототипы показывают, как именно нужно использовать те или иные библиотеки,
как правильно их конфигурировать, как правильно совмещать версии разных библиотек и т.д. 

## Сохраняется ли авторство у разработчиков прототипов ?

Да, в разделах описания прототипа присутствует поле *Authors*.

## На каких технологиях реализован проект ?

В данный момент SS-иерархия реализована на основе git-репозиториев, размещаемых на *GitHub*. Каждый репозиторий содержит
ровно один SS-прототип. Ирархические отношения прототипов реализованы при помощи http-ссылок, размещаемых в их
readme-документах.

## Предполагается ли платное использование сервиса ?

Сам по себе сервис *SoftSpider* предполагает бесплатное использование.

Существующие на данный момент прототипы разработаны под лицензией MIT и находятся в открытом доступе.

В то же время на разработчиков прототипов в *SoftSpiders* не накладывается каких-либо лицензионных ограничений.  
Прототипы могут разрабатываться под любой лицезией, могут быть приватными (см. ниже), могут распространяться как на
бесплатной, так и на платной основе.

### Приватные прототипы

Определённая категория прототипов может быть закрыта для бесплатного доступа. 
Предполагается, что к таким прототипам доступ будет возможен только обладателями специальных учётных записей. 

Политика доступа к приватным прототипам пока не определена.

#### Открытые ссылки на приватные прототипы

Закрытие репозиториев приватных прототипов не обязательно относится к ссылкам на эти прототипы из других репозиториев.    
Так например, если открытый прототип имеет ссылку на закрытый прототип-потомок, то эта ссылка может оставаться видимой.

## Что делать, если у зависимостей изменяются версии ?

Каждый прототип создаётся на каком-то определённом наборе библиотек, фреймворков и прочих зависимостей, версии которых
так или иначе фиксируются в его исходных конфигурационных файлах (pom.xml, package.json, ...).
Если у зависимостей прототипа появляются новые версии, то необязательно что-то предпринимать, поскольку прототип и на
старых версиях продолжает сохранять своё главное качество - служить основой для других разработок.  
В то же время актуализация прототипа путём поддержки новых версий, конечно, приветствуется. 

В случае, если при появлении новых версий у прототипа появляются новые свойства, возможны дополнительные варианты:
- поддержка новых версий с расширением набора свойств прототипа 
- создание прототипа-потомка, поддерживающего новый расширенный набор свойств   

---

# Словарь используемых тегов

Проект *SoftSpiders* имеет собственный  [**словарь тегов**](SoftSpiderTags.md#словарь-тегов), используемых при разметке
прототипов.
  
Ниже приводятся основные правила организации работы с тегами. 

## Правила именования тегов

При именовании тегов можно использовать только строчные буквы латинского алфавита, знак дефиса и цифры, причём имена
тегов должны начинаться с буквы.

В дальнейшем возможны некоторые из этих правил могут быть ослаблены.  


## Теги - синонимы

В скобках словаря тегов указаны теги-синонимы, которые являются его полноценными элементами.

## Зависимости тегов

Стрелками '->' в *словаре тегов* обозначаются *теги-зависимости*. Использование зависимостей позволяет сокращать
разметку прототипов.    
То есть, если, например есть в словаре тегов есть зависимости

```
jersey -> java, rest
rest -> api, http
``` 

, то наличие в разметке узла SS-иерархии тега *rest* означает одновременное наличие там тегов *api, http*, а наличие
тега *jersey* означает одновременное наличие там тегов *java, rest, api, http*.  
Поэтому вместо подразумеваемого полного - **эффективного набора тегов** (см. ниже) *jersey, java, rest, api, http* при разметке прототипов можно и даже рекомендуется использовать только *jersey*.

##  Эффективные наборы тегов

При построении SS-иерархии учитываются ***эффективные наборы тегов*** - те наборы, которые определяются с учётом всех, в
том числе транзитивных зависимостей.

Граф зависимостей тегов не должен иметь циклов. Поэтому иерархия зависимостей тегов, также как и SS-иерархия, является
DAG-иерархией.

## Пояснения к тегам

Имена некоторых тегов могут требовать расшифровки или пояснения. Для этого в словаре используются двоеточия.

Например, смысл тега *hapi* в контексте *словаря тегов* поясняется таким образом: 

```
hapi -> api, backend, node: небольшой фреймворк, использующийся для разработки web-приложений на NodeJS 
```

Стоит отметить, что здесь поясняется именно *hapi*, а не его теги-зависимости: *api, backend, node*.

## Изменяемость словаря

Словарь тегов *SoftSpiders* является изменяемым, как правило, в сторону расширения. Изменения словаря выполняются
участниками проекта.

---

# Текущее состояние проекта

В настоящее время *SoftSpiders* находится в переходном состоянии от прототипа к MVP.

*SoftSpiders* имеет несколько проектов-стартеров, некоторые из которых уже сейчас используются сторонними разработчиками.
То, что их пока немного, объясняется тем, что до сих пор рост SS-иерархии за редкими исключениями происходил в режиме
proof-of-concept, снизу-вверх, что, разумеется, приводило к преимущественному росту её нижних, базовых уровней.

Программная поддержка, автоматизирующая процессы работы с прототипами планируется, но её пока нет, если к таковой
не относить используемые возможности GitHub: хостинг SS-репозиториев, поисковик GitHub, организацию связей между
прототипами через ссылки README.md и т.п.

## Эволюция и перспективы проекта

Наполнение базы знаний проекта продолжается.  
Очевидно, что чем выше будет уровень  SS-иерархии, тем большим набором
свойств и большей сложностью будут обладать прототипы, тем большей будет стоимость добавления новых свойств, поскольку с
ростом числа используемых инструментов будет расти и стоимость решения проблем их совместимости.
А значит - тем большую ценность решения *SoftSpiders* будут иметь для разработчиков.

## Что нужно прямо сейчас

- Разработка правил для участников проекта - раздела типа
[How to Contribute](https://reactjs.org/docs/how-to-contribute.html), но пока попроще 
- Разработка манифеста проекта

## Что потребуется в ближайшее время

- Разработка json-представления для прототипов
- Сайт проекта (в основе статический), который бы включал, как минимум:
  - Систему навигации по SS-иерархии
- Система мотивации участников
    - геймификация
    - рейтинги разработчиков
    - рейтинги прототипов
    - ...

### Что будет нужно всегда ?

Наполнение базы знаний прототипами - её главным содержанием

---

# Приложения

## Правила разработки прототипа

В целом прототип разрабатывается как обычный проект. Он может быть написан с нуля, может быть fork-ом или копией
другого проекта. В двух последних случаях в README проекта указывается ссылка на оригинальное авторство.

### Английский язык

Поскольку проект *SoftSpiders* ориентирован на привлечение широкого круга участников, в том числе зарубежных, все тексты
репозитория SS-прототипа (код, комментарии в коде, комментарии коммитов, документация прототипа и т.п.) разрабатываются
на английском.

### Главный документ

Главный документ SS-прототипа находится в файле README.md, правила оформления которого описаны
[здесь](#правила-оформления-документа-readmemd-ss-прототипа).


### Автотесты

Крайне желательным свойством прототипа является покрытие его кода автотестами. Впоследствии для отдельных категорий
прототипов наличие автотестов может стать обязательным.  

Потребность в наличии автотестов обусловлена перспективами развития проекта *SoftSpiders*. Чем дальше он будет
развиваться, тем сложнее будут становиться прототипы, тем труднее будет вручную проверять их работоспособность,
особенно, если поток запросов на включение прототипа в SS-классификатор будет большим.

Ну и, разумеется, никто не отменял связь между наличием автотестов и качеством программных проектов. В частности, для 
прототипов-стартеров автотесты всегда являются существенным плюсом.

#### Подключение средств Continuous Integration

Ещё более ценным свойством проекта является *ci* - подключение средств *Continuous Integration* для автоматического
запуска тестов при поступлении изменений (коммитов) в репозиторий проекта.

На GitHub *Continuous Integration* поддерживается средствами [*Travis CI*](https://travis-ci.com/) и
[*GitHub Actions*](https://github.com/features/actions).

## Правила оформления README

Файл *README.md*, находящийся в корневой директории репозитория, является его главным документом.  
Он оформляется в синтаксисе markdown (желательно на диалекте GitHub).

### Разделы главного документа

Ниже перечисляются правила оформления наиболее часто использующихся разделов README в синтаксисе markdown - в том
порядке, в каком они должны следовать в самом документе.

Разделы, названия которых ниже по тексту помечены звёздочками, являются обязательными для указания в README проекта. 


#### Первая строка - принадлежность к *SoftSpiders* *

Признаком принадлежности репозитория к проекту *SoftSpiders* является наличие строки *'SOFTSPIDERS'* в начале первой
строки файла *README.md*, как здесь:

```
SOFTSPIDERS
...
```

#### Название проекта *

Название проекта указывается в заголовоке markdown первого уровня:

```
# rest-api-java-jersey
```

#### Раздел *Feature tags* *

Описывает набор тегов-свойств прототипа, например:

```
## Feature tags

- hooks
- react
- test
```

#### Раздел *Authors* *

В разделе перечисляются авторы прототипа с указанием распределения ролей, если это нужно, например:

```
## Authors

* [Dennis Kortsch](https://github.com/DennisKo) - original code
* [Alexander Lapygin](https://github.com/AlexanderLapygin) - catching in [Soft Spiders Net](https://github.com/softspider)

```

#### Раздел *Inspired by*

При желании автор может перечислить источники, вдохновившие его на создание проекта. Например:

```
## Inspired by

[An Apollo Server & Client in a yarn Workspace deployed with Zeit 2.0](https://github.com/DennisKo/zeit-now-next-apollo-typescript-example)
```


#### Раздел *Direct ancestors*

В разделе перечисляются, если они есть, ссылки на непосредственные проекты-предки SS-иерархии. Например:

```
## Direct ancestors

- [Minimal Next in TypeScript](https://github.com/softspider/next-typescript)
- [Zeit Now "HelloWorld" example](https://github.com/softspider/now)
```

Если у проекта нет предков, раздел не включается в документ.

#### Раздел *Direct descendants*

В разделе перечисляются, если они есть, ссылки на непосредственные проекты-потомки SS-иерархии. Например:

```
## Direct descendants

- [Minimal Next in TypeScript](https://github.com/softspider/next-typescript)
- [Zeit Now "HelloWorld" example](https://github.com/softspider/now)
```

Если у проекта нет потомков, раздел не включается в документ.

#### Раздел *Requirements*

В разделе перечисляются программные инструменты, которые должны быть установлены на компьютере разработчика, для того,
чтобы с проектом можно было работать. При этом указываются только те зависимости, которые не подключаются средствами
сборки самого проекта (npm, maven, gradle, ...). Например:

```

## Requirements

* [*Java 7*](https://www.oracle.com/technetwork/java/javase/downloads/java-archive-downloads-javase7-521261.html)
* [*Apache Maven*](https://maven.apache.org/)
* Some servlet container for deploying and running: [*Apache Tomcat*](http://tomcat.apache.org/), [*Jetty*](https://www.eclipse.org/jetty/), ...

```

#### Раздел *Install*

В разделе указывается команда, которую необходимо выполнить для подключения зависимостей проекта. Например:

```
## Install

'''
yarn
'''
```

#### Раздел *Run test*

При наличии в прототипе автотестов, в нём указывается команда, которую необходимо выполнить для их запуска. Например:

```
## Run test

'''
yarn test
'''
```

#### Раздел *Run*

В разделе указывается команда, которую необходимо выполнить для запуска прототипа.
Например:

```
## Run

'''
yarn start
'''
```

#### Раздел *Useful materials*

Перечисляются ссылки на материалы, которые могут быть полезными для знакомства со свойствами проекта.


#### Раздел *License*

### License

Licensed under the [MIT license](LICENSE).
